---
title: Branch Review
description: Branch Review in Cypress Cloud surfaces the impact of Pull Requests on your test suite. Compare test results between branches and learn best practices for grouping test runs.
sidebar_position: 50
---

<ProductHeading product="cloud" />

# Branch Review

:::info

##### <Icon name="question-circle" color="#4BBFD2" /> What you'll learn

- How to compare test results between branches in Cypress Cloud
- How Branch Review surfaces the impact of Pull Requests on your test suite
- How to compare **any** two runs, if not using a Pull Request workflow
- Best practices for grouping test runs

:::

Cypress Branch Review allows you to quickly identify the different impacts a Pull Request might have on your test suite in a single view.
Compare which tests are failing, flaky, pending, added, or modified between the source and base branches. If enabled on your account,
UI Coverage or Cypress Accessibility changes between runs will also appear here.

Branch Review is useful even if you do not have a Pull Request workflow, because it allows you to compare any two runs of your choice.
These might represent different builds of the application, changes in test code, or results from nightly runs. This page will use
the example of a Pull Request made using the GitHub integration, but this integration is not required in order to use Branch Review.

A common scenario throughout the software development lifecycle (SDLC) is an engineer's **feature** branch that will be merged into the
repo's **develop** or **main** branch. Here's how this scenario appears in Branch Review:

<DocsImage
  src="/img/cloud/features/branch-review/branch-review.png"
  alt="Cypress Branch Review"
/>

Without Branch Review, pinpointing changes in your test suite's results requires a manual side-by-side comparison between your newly-introduced branch's test runs and your base branch's test runs. This sub-optimal workflow often fails to answer the fundamental questions, _what changed_ and _why?_ You might be left wondering if the same tests are flaky between branches, when new failures were introduced, or if you added sufficient test coverage to your new branch.

## Getting Started

The key to the Branch Review area is a comparison between a **Base** run and a **Changed** run.
The Changed run is the main subject of the comparison, often associated with an incoming Pull Request. The Base run is the starting point for comparison.

### Accessing Branch Review

There are a number of ways to get to Branch Review depending on where you are looking at your Cypress results. In all cases, once you've picked Changed run, you can adjust the automatically-selected Base run to any branch or run in the project to dial in the comparison you are most interested in.

### From the project list

The project card shows three active branches for the project. You can click through to any of these to enter Branch Review focused on that branch.

<DocsImage
  src="/img/accessibility/core-concepts/branch-review-project-card.png"
  width="40%"
  alt="A card showing the name of an example project and related branches to choose."
/>

### From the main navigation

When a project is open, select "Branches" in the main navigation to see a full, filterable list of available branches and choose one to set as the source of the Changed run.

<DocsImage
  src="/img/accessibility/core-concepts/branch-review-side-nav.png"
  width="40%"
  alt="The main Cypress Cloud navigation showing Latest Runs, Branches, and Analytics menu items. An arrow points to Branches."
/>

### From the run overview page

Click the branch name associated with the run. This will take you to Branch Review with that run pre-selected as the Changed run. This is a great way to investigate a specific run with an unexpected outcome in the tests.

<DocsImage
  src="/img/accessibility/core-concepts/branch-review-run-card.png"
  alt="Two cards showing various details about Cypress test runs, including pass/fail counts and metadata. An arrow points to the branch name."
/>

### From a Pull Request

Click the "View all changes introduced in this branch" link at the bottom of the Test Results table. You will enter branch review with the current PR's branch and latest run pre-selected as the Changed run.

<DocsImage
  src="/img/accessibility/core-concepts/branch-review-pull-request.png"
  alt="A Pull Request comment from Cypress with an arrow pointing to the 'View all changes introduced in this branch' link. Test results and some accessibility score and violation information is also visible in the comment. The project has an 86.86% accessibility score, with  9 failed elements. Failed rule counts are 1 critical, 1 serious, 3 moderate, and 0 minor."
/>

## Integrating with Pull Requests

Pull Requests in Branch Review work by leveraging the Cypress Cloud GitHub integration to query the GitHub API for branches with Pull Requests. Your project will first need to be connected to a GitHub repository. If you haven't already, follow the steps in [Install the Cypress GitHub app](/cloud/integrations/source-control/github#Install-the-Cypress-GitHub-app) to connect your project to GitHub.

When Pull Requests are connected, you will be able to select runs by the associated PR:

<DocsImage
  src="/img/cloud/features/branch-review/pr-in-branch-review.png"
  width="40%"
  alt="A list of latest pull requests in the Changed run dropdown menu"
  className="mb-1"
/>

:::info

**Note:** If you do not see PR # tags associated with a branch, you may need to [pass PR numbers](/app/continuous-integration/overview#CI-Build-Information) to runs as environment variables. This helps ensure Cypress Cloud can map PR data correctly.

:::

#### Latest Runs

If the selected branch has a PR associated and a PR # passed via CI, there is an additional callout on the top of the overview tab of the **Latest runs** page which directs to the Branch Review.

<DocsImage
  src="/img/cloud/features/branch-review/branch-review-available.png"
  alt="Branch Review available banner"
/>

## Branch Details

### Review Header

The header includes the Git commit message, PR selector, PR status, and base and feature branch labels with the Cypress Cloud test run ID number (#).

If there are multiple Pull Requests open for the same branch, you can select the Pull Request you want to review from the dropdown to the right of the commit message.

Clicking the branch label will link you directly to the appropriate [run overview](/cloud/features/recorded-runs#Overview-tab) and hovering on these elements exposes additional run meta data.

<DocsImage
  src="/img/cloud/features/branch-review/branch-review-header.png"
  alt="Branch Review Header"
/>

### Review Test Status

:::info

**Note:** Recording exactly one run for every commit is the best way to ensure complete and accurate comparisons. See our [best practices](/cloud/features/branch-review#Best-Practices) on grouping multiple `cypress run` calls under one run.

:::

When on the review screen, you will see the Failures, Flaky, Pending, Added, and Modified tabs. Each tab will show you the specs that fall into that category. You can click on a test to view the test details.

<DocsImage
  src="/img/cloud/features/branch-review/branch-review-details.png"
  alt="Branch Review Details"
/>

:::note

**Review Test Status**

1. Details of which branches and runs are compared. If a Pull Request is detected, Pull Request details will be here.
1. Links to key differences in test information like new failures and flaky tests. Note that all numbers and scores refer to the Changed run.
1. [UI Coverage](https://on.cypress.io/ui-coverage-trial?utm_medium=cloud-br&utm_source=docs.cypress.io&utm_term=&utm_content=UI+Coverage) changes.
1. [Cypress Accessibility](http://on.cypress.io/accessibility-trial?utm_medium=cloud-br&utm_source=docs.cypress.io&utm_term=&utm_content=Cypress+Accessibility) changes.
1. See what has changed in the specific status you have opened, for example:
   - <img
       className="br-ui inline-block"
       src="/img/cloud/features/branch-review/test-status-up.png"
       alt="up arrow and number 3 marked in red colored text"
     /> total number introduced in your branch
   - <img
       className="br-ui inline-block"
       src="/img/cloud/features/branch-review/test-status-down.png"
       alt="down arrow and number 4 marked in green colored text"
     /> total number decreased or resolved in your branch
   - <img
       className="br-ui inline-block"
       src="/img/cloud/features/branch-review/test-status-total.png"
       alt="number 4 marked in gray colored text"
     /> total count, for example, _3 new and 1 existing_
1. The test state (failed, flaky, pending) is also indicated at the spec level
   - _new_ = the state was <u>not</u> previously captured, but now <u>is</u> captured<br />(newly pending tests can imply an `it.skip()` was not removed)
   - _existing_ = the state <u>was</u> previously captured and now <u>is still</u> captured
   - _resolved_ = the state <u>was</u> previously captured but now is <u>no longer</u> captured

:::

### Review Test Comparison

Navigating into the test detail view reveals a side-by-side comparison of the test results on both branches, as well as, artifacts so you can compare before vs. after your PR. This can help narrow the focus on changes introduced or resolved on either branch and elevate the source of flake within tests throughout different attempts. Review the test definition panel for diff snapshots to help quickly determine changes in test code.

<DocsImage
  src="/img/cloud/features/branch-review/test-comparison.png"
  alt="Test Comparison View"
/>

:::note

**Review Test Comparison**

1. Base branch results

2. Feature branch results

3. Test Replay and artifacts

4. Test attempts (descending order)

5. Code change diffs

:::

## Troubleshooting

### Note on Available Data for Pull Requests

Branch Review is a powerful tool to compare two branches with recorded runs to Cypress Cloud. There are factors that can impact what is available to review between a feature and base branch. For example, whether or not a branch at a particular commit has a run recorded to Cypress Cloud will affect what is displayed.

The following captures this scenario across both branches:

|              Base Branch              |            Feature Branch             | What Branch Review Displays                          |
| :-----------------------------------: | :-----------------------------------: | ---------------------------------------------------- |
| <Badge type="success">has run</Badge> | <Badge type="success">has run</Badge> | Comparison data using both found runs                |
| <Badge type="success">has run</Badge> |  <Badge type="danger">no run</Badge>  | Comparison data using last run on feature branch     |
|  <Badge type="danger">no run</Badge>  | <Badge type="success">has run</Badge> | Non-comparison data with found feature run           |
|  <Badge type="danger">no run</Badge>  |  <Badge type="danger">no run</Badge>  | Non-comparison data using last run on feature branch |

If the required runs for comparison are not available, you can use the manual selection dropdowns to compare two suitable runs, if they exist in Cypress Cloud.

## Best Practices

### Grouping Test Runs

Cypress Cloud allows for [grouping recorded tests](/cloud/features/smart-orchestration/parallelization#Grouping-test-runs) together under a single run. This means multiple `cypress run` calls can be labeled and associated to a single run in Cypress Cloud.

Recording multiple test runs per commit without grouping will cause issues, as Branch Review relies on the _latest_ run. Therefore, recording one run per commit and utilizing grouping is essential to improving effectiveness and ensure an accurate comparison between branches.

### Missing Runs in Pull Request Comparisons

If a run is missing on either the merge base or feature commit of the PR, a banner is displayed specifying which commit is missing the run with a link to it on GitHub.

## See Also

- Read about [multi-repo implementation](/cloud/account-management/projects#Multi-repo-Implementation) best practices in Cypress Cloud. Even if your test code and application code are not colocated, you maybe be able to connect your test runs to specific commits and pull requests in your application.
